Skip to content

perf(route): match routes by walking a trie of route segments - #7939

Open
FarhanAliRaza wants to merge 1 commit into
mainfrom
farhan/upbeat-thompson-ftzgzb
Open

FarhanAliRaza wants to merge 1 commit into
mainfrom
farhan/upbeat-thompson-ftzgzb

Conversation

@FarhanAliRaza

@FarhanAliRaza FarhanAliRaza commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

All Submissions:

  • Have you followed the guidelines stated in CONTRIBUTING.md file?
  • Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

  • Performance improvement (non-breaking change): backend route matching

Describe your changes

get_router resolved a path by trying each route's regex in turn until one matched. Every event calls the router (EventNamespace.on_event, App.get_load_events). An lru_cache makes repeat paths a dictionary hit, but each new path paid one regex call per route.

Routes Regex scan, new path Trie, new path
10 1.19 µs 0.48 µs
100 5.38 µs 0.49 µs
1000 49.11 µs 0.49 µs

It also kept test_route_matching flaky after #7878. CodSpeed runs Python with PYTHONMALLOC=malloc, and every fullmatch allocates through glibc. That was about half the benchmark's measured time, and glibc's heap state moved it between 90 and 96.8 ms. 24 of the 59 CodSpeed reports on PRs based after #7878 flag it, including docs-only and README-only PRs.

The trie. Following the radix-trie design of routers like Rust's matchit:

  • Each level matches one path segment. Static children are keyed by the segment with ASCII letters lowercased. Each node has one child for [arg] and one for [[arg]], plus a slot for a [[...splat]] route.
  • Every route keeps the rank the regex scan tried it in: route_specificity, ties in the order given.
  • A lookup walks the path, collects the routes that match, and returns the lowest-ranked one. A branch whose best rank can't beat the current answer is skipped, so a typical lookup is a single walk down the path.

Unlike matchit, it doesn't let a static segment win at each position. The winner is still the route the regex scan picked, so on_load events resolve exactly as before.

Same matching rules as the regexes:

  • ASCII-only case folding (/\N{KELVIN SIGN}it still doesn't match kit).
  • One trailing slash stripped from the path, plus one more allowed by the route.
  • [arg] can match an empty segment.
  • [[arg]] matches nothing or one non-empty segment.
  • A catch-all stops at a newline, as the regex . did.
  • /index resolves to the index route.
  • Duplicate templates resolve as before.

test_get_router_matches_the_regex_scan keeps the old regex scan as a reference, built from the unchanged public get_route_regex and route_specificity. It checks that both pick the same route on 24,000 seeded random route tables and paths: mixed case, non-ASCII, empty segments, extra slashes, /index and newlines.

One behavior change: a [[...splat]] that isn't the route's last segment now raises ValueError in get_router. verify_route_validity already rejects such routes for every page added to an app, so only a direct get_router call with an invalid route sees it.

Benchmark. test_route_matching keeps only its 1000-route case, as a guard against going back to scanning every route, and now does 400 lookups per measured call (235 µs uninstrumented).

  • Before: running under CodSpeed's settings locally (PYTHONMALLOC=malloc, fixed cache sizes, no address randomization), changing only the size of the environment moved the old benchmark's instruction count by up to 3.7%.
  • Now: the instruction count moves 0.02% and the cache-weighted estimate 0.83%.

New Feature Submission:

  • Does your submission pass the tests?
  • Have you linted your code locally prior to submission?

Changes To Core Features:

  • Have you added an explanation of what your changes do and why you'd like us to include them?
  • Have you written new tests for your core changes, as applicable? The equivalence test above, plus explicit tests for ranking ties, segment edge cases and the catch-all error.
  • Have you successfully ran tests with your changes locally?
    • tests/units/test_route.py, tests/units/test_app.py and tests/units/utils/test_exec.py pass, as do ruff and pyright on the changed files.
    • The full unit run fails only in two places, and neither is from this change:
      • The Playwright tests in tests/units/reflex_bench/drivers/test_browser.py need a Chromium build this container doesn't have.
      • Two pyright errors in tests/units/components/graphing/test_plotly.py also fail on unmodified main locally.
    • CI runs everything.

https://claude.ai/code/session_01LwJUCWYQL5BocrPjnH5hFX


Generated by Claude Code

View guided diff Turn on auto-fix

get_router tried each route's regex in turn until one matched, so
resolving a path the router had not seen cost one regex call per route:
about 1.2, 5.4 and 49 us for 10, 100 and 1000 routes. Each call also
allocated through glibc, about half of test_route_matching's measured
time, and the allocator's heap state made that benchmark flip by about
7% between commits on CodSpeed.

Routes now go into a trie with one level per path segment: static
children keyed by the ASCII-folded segment, plus one child each for
[arg] and [[arg]] and a slot for [[...splat]]. A route keeps the rank
the regex scan tried it in (route_specificity, ties in order given), and
a lookup returns the lowest-ranked route the path matches, skipping any
branch whose best rank cannot win. A new path takes about 0.5 us at any
table size.

Matching stays exactly what the regexes did: ASCII-only case folding,
one trailing slash allowed on top of the one stripped, [arg] matching an
empty segment, [[arg]] matching nothing or one non-empty segment, and a
catch-all stopping at a newline as the regex dot did. A test checks the
trie against the regex scan on 24,000 random route tables and paths. A
catch-all that is not the last segment now raises, as
verify_route_validity already did for every page route.

test_route_matching keeps only its 1000-route case, as a guard against a
return to scanning, with 400 lookups per measured call.

Claude-Session: https://claude.ai/code/session_01LwJUCWYQL5BocrPjnH5hFX
@FarhanAliRaza
FarhanAliRaza requested review from a team and Alek99 as code owners November 19, 2026 17:34
@greptile-apps

greptile-apps Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge.

Summary

Replaces the backend’s route-by-route regex scan with a tree of path segments while preserving route priority and cached lookups.

  • New paths find their page by walking route segments.
  • Catch-all routes must end before the router accepts them.

No actionable issues found.

Reviews (1) · Last reviewed commit: "Match routes by walking a trie of route ..." · Reviewed by Greptile

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 5 files

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread reflex/route.py Resolved
@codspeed

codspeed Bot commented Nov 19, 2026

Copy link
Copy Markdown

Merging this PR will improve performance by ×13

2 warnings

⚠️ 15 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚠️ 4 benchmarks with a significant change ran on different hardware

Their base and head results were measured on machines with a different CPU, core count or memory, so the changes might not come from the code. Run base and head on the same runner type.

Learn more about Macro Runners

See affected benchmarks

⚡ 4 improved benchmarks
✅ 140 untouched benchmarks
⏩ 10 skipped benchmarks1

Performance Changes

Benchmark BASE HEAD Efficiency
⚡ test_route_matching[1000] 90 ms 4.4 ms ×20
⚡ test_route_table_construction[1000] 377.8 ms 26.7 ms ×14
⚡ test_route_table_construction[100] 36 ms 2.8 ms ×13
⚡ test_route_table_construction[10] 3,497.4 µs 403.3 µs ×8.7

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.


Comparing farhan/upbeat-thompson-ftzgzb (beb00b6) with main (baa7318)

Open in CodSpeed

Footnotes

  1. 10 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

Copy link
Copy Markdown
Contributor Author

The one red check, app-harness-playwright (redis, 3.12, 1) behind integration-tests-gate, doesn't come from this PR.

  • What failed: tests/integration/tests_playwright/test_client_error.py::test_state_mismatch_prompts_reload[prod-chromium] errored during teardown. The other 299 tests in that leg passed. The same test, on the same commit, passed in the other 35 jobs, including the same shard with the memory store on 3.12 and with redis on 3.11, 3.13, 3.14 and 3.15.
  • Why it failed: a race inside the test. The mismatch_reports fixture swaps frontend_exception_handler for a lambda that collects reports, and restores the real handler at teardown. The test's last step clicks "Reload". When that reload's hydrate reports the unknown substate only after teardown has restored the real handler, the handler logs [Reflex Frontend Exception] ... no dispatch function registered. The harness's error capture then fails the test.
  • Why it isn't the router: this PR only changes how a path is matched to a route. The page here is /, which resolves to index exactly as before. test_get_router_matches_the_regex_scan checks that the new and old routers agree on every path.

Re-running the failed job isn't available to this session (GitHub returns 403), so it needs a manual re-run.


Generated by Claude Code

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant